FE-806: Agent prompt-resource composition, runtime manifests, and snapshot contexts#169
Merged
Merged
Conversation
This was referenced Jun 4, 2026
Contributor
Author
|
Semgrep found 1 Detected a call to |
PR SummaryLow Risk Overview Planning and triage. Scoping. Fixtures. Adds Reviewed by Cursor Bugbot for commit be0b42b. Bugbot is set up for automated code reviews on this repo. Configure here. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 8a9ab43. Configure here.
| stance: mapping.stance, | ||
| basis: 'explicit', | ||
| rationale: edge.rationale, | ||
| }); |
There was a problem hiding this comment.
Port emits duplicate graph edges
Medium Severity
The Bilal port loop appends every mapped edge to brunchEdges without deduplicating. After decision collapse remaps multiple alternative UUIDs to one decision local_id, distinct source edges can become identical tuples (same source, target, category, and stance). Committed fixtures then contain duplicate rows, skewing edge counts and seed graph integrity.
Reviewed by Cursor Bugbot for commit 8a9ab43. Configure here.
There was a problem hiding this comment.
Pull request overview
This PR advances FE-806 by migrating Brunch prompting from the legacy src/.pi/context/ prompt-pack subtree into a new src/agents/ composition layer with code-owned resource manifests, typed selected-spec context renderers, and grade-gated tool policy. It also introduces namespaced /brunch:* commands, updates several tests and READMEs to match the new topology, and adds Bilal spec-graph ports as development seed fixtures.
Changes:
- Introduces
src/agents/prompt composition (compose.ts,state.ts) plus prompt resources (goals/strategies/lenses/methods/definitions) and context renderers (cwd/graph/node), and updates.piprompting to use these manifests and contexts. - Replaces the old
/brunchworkspace command with/brunch:switchand stubs additional namespaced commands; updates the Pi extension shell registry accordingly. - Adds
.fixtures/seed-specs/bilal-port/seed fixtures + port script, and syncs planning/docs to reflect the new delivery-cut state.
Reviewed changes
Copilot reviewed 86 out of 92 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| src/web/app.test.tsx | Improves RPC client disposal testing by injecting a close spy. |
| src/session/workspace-session-coordinator.ts | Exports WorkspacePostureState for use in prompt composition typing. |
| src/rpc/handlers.test.ts | Adds coverage for session.exchanges readiness behavior. |
| src/README.md | Updates repository topology notes for the new src/agents/ layout. |
| src/print-snapshot.test.ts | Fixes test typing for session manager state. |
| src/brunch-tui.ts | Wires selected-spec prompt context + dynamic graph deps into the runtime factory. |
| src/brunch-tui.test.ts | Updates command/shortcut expectations and tool activation assertions for /brunch:*. |
| src/agents/strategies/step-wise-disambiguate.md | Adds strategy resource markdown. |
| src/agents/strategies/step-wise-decision-tree.md | Adds strategy resource markdown. |
| src/agents/strategies/propose-graph.md | Adds strategy resource markdown. |
| src/agents/strategies/project-graph.md | Adds strategy resource markdown. |
| src/agents/state.ts | Implements readiness-gated manifests and elicit tool policy derivation. |
| src/agents/state.test.ts | Tests manifest/tool gating by readiness grade. |
| src/agents/README.md | Documents completed migration from .pi/context to src/agents. |
| src/agents/methods/run-structured-exchange.md | Adds method guidance resource markdown. |
| src/agents/methods/review-for-gaps.md | Adds method guidance resource markdown. |
| src/agents/methods/read-snapshot.md | Adds method guidance resource markdown. |
| src/agents/methods/infer-and-capture.md | Adds method guidance resource markdown. |
| src/agents/methods/generate-proposal.md | Renames/expands candidate proposal guidance as a method resource. |
| src/agents/methods/commit-graph.md | Adds method guidance resource markdown. |
| src/agents/lenses/oracle.md | Adds lens resource markdown. |
| src/agents/lenses/intent.md | Adds lens resource markdown. |
| src/agents/lenses/design.md | Adds lens resource markdown. |
| src/agents/index.ts | Exports new compose/state/context APIs from src/agents. |
| src/agents/goals/grounding-advance.md | Adds goal resource markdown. |
| src/agents/goals/elicit-expand.md | Adds goal resource markdown. |
| src/agents/goals/commit-converge.md | Adds goal resource markdown. |
| src/agents/goals/capture-posture.md | Adds goal resource markdown. |
| src/agents/definitions/reviewer.md | Adds agent definition resource markdown (future role). |
| src/agents/definitions/elicitor.md | Adds agent definition resource markdown (foreground agent). |
| src/agents/contexts/node.ts | Adds selected-spec node neighborhood context renderer. |
| src/agents/contexts/node.test.ts | Tests node context renderer output bounds and not-found behavior. |
| src/agents/contexts/index.ts | Barrel export for context renderers. |
| src/agents/contexts/graph.ts | Adds selected-spec graph overview context renderer with lens emphasis. |
| src/agents/contexts/graph.test.ts | Tests graph context renderer ordering/bounding. |
| src/agents/contexts/cwd.ts | Adds selected workspace/spec/session/posture context renderer. |
| src/agents/contexts/cwd.test.ts | Tests cwd context renderer content. |
| src/agents/compose.ts | Implements prompt composition output with manifests and routing rules. |
| src/agents/compose.test.ts | Tests compose output structure and manifest legality. |
| src/agents/architecture.test.ts | Enforces removal of legacy .pi/context and checks key resource content. |
| src/.pi/README.md | Updates .pi guidance: prompting is adapter-only; resources live in src/agents. |
| src/.pi/pi-extension-shell.ts | Switches shell registration to commands + prompting provider; exposes new exports. |
| src/.pi/extensions/workspace-dialog.ts | Updates messaging for /brunch:switch and trims command registration (moved). |
| src/.pi/extensions/prompting.ts | Replaces legacy prompt-pack composition with composeAgentPrompt + context renderers. |
| src/.pi/extensions/operational-mode.ts | Uses new activeToolNamesForPosture policy with readiness grade input. |
| src/.pi/extensions/graph/index.ts | Uses dynamic specId; returns typed details; uses renderNodeContext for neighborhood. |
| src/.pi/extensions/commands.ts | Adds /brunch:* namespaced commands and shortcut registration. |
| src/.pi/context/README.md | Deletes legacy prompt-pack README. |
| src/.pi/context/prompt-packs/structured-exchange.md | Deletes legacy prompt pack. |
| src/.pi/context/prompt-packs/elicitor.md | Deletes legacy prompt pack. |
| src/.pi/context/prompt-packs/elicit.md | Deletes legacy prompt pack. |
| src/.pi/context/prompt-packs/capture-analysis.md | Deletes legacy prompt pack. |
| src/.pi/context/prompt-packs/brunch-base.md | Deletes legacy prompt pack. |
| src/.pi/context/compose-brunch-prompt.ts | Deletes legacy prompt-pack composer. |
| src/.pi/context/builders/structured-exchange-context.ts | Deletes legacy empty builder. |
| src/.pi/context/builders/README.md | Deletes legacy builder README. |
| src/.pi/context/builders/readiness-context.ts | Deletes legacy empty builder. |
| src/.pi/context/builders/graph-context.ts | Deletes legacy empty builder. |
| src/.pi/tests/prompting.test.ts | Updates tests to assert manifests + selected-spec context integration in prompts. |
| src/.pi/tests/operational-mode.test.ts | Updates tool policy expectations for elicit mode. |
| src/.pi/tests/mention-autocomplete.test.ts | Minor test typing/formatting update. |
| src/.pi/tests/graph-tools.test.ts | Adds end-to-end test for read_graph neighborhood content/details. |
| src/.pi/tests/extension-registry.test.ts | Updates registered commands list to new /brunch:* command set. |
| package.json | Updates build:pi-assets to package src/agents resources into dist/agents. |
| memory/PLAN.md | Syncs delivery-cut plan: marks FE-806 done; reshapes next priorities. |
| memory/cards/live-graph-observer--mise-en-place.md | Removes retired mise-en-place card. |
| memory/cards/graph-tool-resilience--graph-write-contract.md | Adds scoped chain card for graph write contract materialization. |
| docs/praxis/ln-skills.md | Adds certainty-posture sequencing guidance. |
| docs/design/REVIEW_SETS.md | Updates review-set payload description to match new graph contract direction. |
| docs/design/GRAPH_MODEL.md | Updates graph model doc (basis semantics, projections, interrogative normalization). |
| docs/archive/PLAN_HISTORY.md | Archives plan history for recently completed work. |
| .oxlintrc.json | Disables unicorn/no-empty-file. |
| .fixtures/workbenches/live-graph-observer/README.md | Updates browser feedback loop guidance to prefer agent-browser. |
| .fixtures/seed-specs/bilal-port/README.md | Documents Bilal port fixtures and mapping rules. |
| .fixtures/seed-specs/bilal-port/macro-view/spec.json | Adds seed spec metadata for Macro View. |
| .fixtures/seed-specs/bilal-port/explorer-ui/spec.json | Adds seed spec metadata for Explorer UI. |
| .fixtures/seed-specs/bilal-port/code-health/spec.json | Adds seed spec metadata for Code Health. |
| .fixtures/seed-specs/bilal-port/_port-script.ts | Adds the one-off porting script to generate Bilal seed fixtures. |
| .fixtures/runs/agents-composition-layer/runtime-posture-proof.md | Adds a deterministic proof note for FE-806 runtime posture. |
| .agents/skills/ln-scope/SKILL.md | Updates skill doc with certainty-posture handling. |
| .agents/skills/ln-plan/SKILL.md | Updates skill doc with posture-dependent sequencing rules. |
| .agents/skills/ln-plan/references/proving.md | Adds proving-posture reference. |
| .agents/skills/ln-plan/references/earned.md | Adds earned-posture reference. |
| .agents/skills/ln-plan/assets/plan-template.md | Updates frontier template to include certainty/posture annotations. |
| .agents/skills/ln-consult/SKILL.md | Updates consult routing with posture-aware guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+89
to
+93
| const METHOD_TOOL_NAMES: Partial<Record<MethodId, readonly string[]>> = { | ||
| 'run-structured-exchange': ['present_question', 'present_options'], | ||
| 'read-snapshot': ['read_graph'], | ||
| 'commit-graph': ['commit_graph'], | ||
| }; |
Comment on lines
+22
to
+25
| - **Current lock:** stable node reference codes, `basis` as | ||
| approval strength (`explicit | implicit`), non-exclusive | ||
| readiness bands, supersession acyclicity, and snapshot | ||
| graph-truth vs active-context separation. Locked. |
Comment on lines
+63
to
+82
| ## Graph basis — approval strength, not mutation path | ||
|
|
||
| ```ts | ||
| type GraphBasis = "explicit" | "implicit" | ||
| ``` | ||
|
|
||
| `basis` is shared by nodes and edges. It records whether the exact | ||
| accepted graph item was user-approved: | ||
|
|
||
| - **`explicit`** — the user directly stated the node/edge, or | ||
| approved that exact node/edge in a review set. | ||
| - **`implicit`** — the user accepted a concept/proposal, and the | ||
| agent materialized specific graph items to match it without | ||
| per-item review (the `propose-graph` direct-commit path). | ||
|
|
||
| `basis` does **not** record the mutation pathway. The pathway lives | ||
| in `change_log.operation` and payload (`commit_graph`, | ||
| `accept_review_set`, post-exchange capture, etc.). Low-confidence | ||
| inferred material still stays outside graph truth until clarified or | ||
| accepted. |
Comment on lines
+49
to
+58
| export function registerBrunchPrompting( | ||
| pi: ExtensionAPI, | ||
| promptContext: BrunchPromptContextProvider | undefined, | ||
| ): void { | ||
| if (!supportsPrompting(pi)) return; | ||
|
|
||
| pi.on('before_agent_start', async (event, ctx) => { | ||
| if (!promptContext) { | ||
| throw new Error('Brunch prompting requires selected spec and workspace context.'); | ||
| } |
lunelson
changed the title
…rule
Add a one-off port of three spec graphs (~916 nodes, ~1866 edges) from
Bilal's spec-elicitation prototype into brunch-shaped JSON fixtures
under .fixtures/seed-specs/bilal-port/. Intended as rich, real
development seed data for the dev SQLite database. Not a probe-run
artifact; sits alongside .fixtures/runs/ rather than inside it. The
porting script is co-located with its output (.fixtures/** is excluded
from the verification harness by project config).
Mapping highlights derived in conversation:
- decision hubs collapse hub-and-spoke into a single decision node
with detail.{chosen_option, rejected[], rationale}
- evidence ports to oracle plane with one synthetic per-spec check
as its realization parent
- risk and design semanticRoles port to context with source-field
curation flags (derived-risk-or-question, derived-design-statement)
- derived_from defaults to dependency, downgraded to support[for]
when target is observational (evidence/assumption)
- authority projects to brunch source; epistemicStatus=inferred maps
to basis=accepted_review_set, others to basis=explicit, with
epistemic flavor concatenated into source
- displayId preserved as bracket suffix in source for traceability
Add an interrogative-content-normalization subsection to
docs/design/GRAPH_MODEL.md under Prompting guidance, codifying the
rewrite rule that motivates the risk-to-context mapping: brunch has
no question kind because intent nodes are claims; questions are
rewritten into the latent declarative (assumption, criterion, or
unresolved-state context), and the discovery-to-resolution arc uses
decision -[supersession]-> context.
Amp-Thread-ID: https://ampcode.com/threads/T-019e91ee-aa39-73d2-a346-a0ae1e55e3b9
Co-authored-by: Amp <amp@ampcode.com>
Adds ln-plan/references/{proving,earned}.md with posture-specific
sequencing doctrine and annotation field sets. ln-plan/SKILL.md gains
§Operating posture and Procedure Step 0 (read .pi/POSTURE.md + load
matching reference) in place of the old §Tracer-bullet sequencing.
ln-scope, ln-consult, and the praxis doc are updated to mirror the
posture split: Posture check / Posture-aware route override with
proving and earned branches.
The earned-mode reference introduces a closure move-set (materialize,
consolidate, name canonically, delete-as-progress, retire bridges,
take-the-bigger-step), a circling-recognition heuristic, sprawl
guardrails, and earned→proving regression handling. Boundaries with
ln-refactor (safe mechanics) and ln-sync (canonical GC) are explicit.
Plan-template adds mandatory Certainty: and Posture annotations:
fields to frontier definitions.
Amp-Thread-ID: https://ampcode.com/threads/T-019e91c8-a351-75ea-b7b0-29be68d448d2
Co-authored-by: Amp <amp@ampcode.com>
Pi parses slash command names as everything between the leading / and
the first whitespace, so a command registered with the literal name
'brunch:switch' is invocable as /brunch:switch -- the same trick the
built-in /skill:<name> registry uses.
Introduce src/.pi/extensions/commands.ts as the registration hub for
the /brunch:* namespace. It owns:
- /brunch:switch - opens the spec/session picker (delegates to the
runBrunchWorkspaceAction helper that still lives
in workspace-dialog.ts as private impl).
- /brunch:continue - notify-only stub for the recover/resume flow.
- /brunch:lens - notify-only stub.
- /brunch:strategy - notify-only stub.
- /brunch:mode - notify-only stub.
- ctrl+shift+b shortcut, preserved with a notify-only warning that
points at /brunch:switch (Pi shortcut contexts cannot switch
sessions yet).
workspace-dialog.ts is reduced to its private dialog action helpers
(runBrunchWorkspaceAction / runBrunchWorkspaceCommand). The retired
BRUNCH_WORKSPACE_COMMAND / BRUNCH_WORKSPACE_SHORTCUT constants,
registerBrunchWorkspaceDialog wrapper, and unused notify-only default
export are removed (pre-release posture - no compat shim).
pi-extension-shell.ts wires registerBrunchCommands in place of
registerBrunchWorkspaceDialog and updates re-exports.
Tests follow the new shape: the extension-registry smoke test now
points at commands.ts instead of workspace-dialog.ts and asserts the
full 5-command registration order; brunch-tui.test.ts uses the new
constants and exercises each stub handler to confirm the notify path.
Amp-Thread-ID: https://ampcode.com/threads/T-019e9276-ae38-770d-92de-a4dcff8b378b
Co-authored-by: Amp <amp@ampcode.com>
lunelson
force-pushed
the
ln/fe-806-agents-composition-layer
branch
from
8a9ab43 to
be0b42b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Builds the agent composition layer: prompt/runtime manifests, selected-spec snapshot context, structured-exchange posture wiring, and rich Bilal-port graph fixtures for exercising the graph-facing agent loop.
Verification
Covered by prompt composition, operational-mode, graph-tool, and seed-fixture tests; latest top-of-stack verification passed via
npm run verify.